<html>

<head>
<meta http-equiv="Content-Language" content="en-us">
<meta name="GENERATOR" content="Microsoft FrontPage 5.0">
<meta name="ProgId" content="FrontPage.Editor.Document">
<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
<title>How To</title>
</head>

<body>

<p>Revised: 
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B %Y" startspan -->20 May 2013<!--webbot bot="Timestamp" endspan i-checksum="39626" --></p>

<h1>How To Instructions</h1>
<p>These instruction assume you going to keep the issues lists source files in a directory named &quot;issues&quot;, 
and the issues lists generated HTML files in a directory named &quot;issues-gh-pages&quot;.</p>
<blockquote>
<p>Keeping the source files and generated HTML files in separate directories 
falls out from the GitHub automatic web page approach: files in a branch named &quot;gh-pages&quot; 
are automatically published by GitHub as web pages.</p>
</blockquote>

<h2>Prerequisites</h2>
<ul>
  <li>Git</li>
  <li>A C++11 compiler. For the moment, that means GCC 4.7 or later.</li>
  <li>Windows is a prerequisite to use the Windows <code>.bat</code> scripts, or
  a POSIX environment is a prerequisite to use the equivalent <code>.sh</code>
  scripts.</li>
</ul>

<h2>Initial setup</h2>
<p><b>Do this once only:</b></p>
<blockquote>
<pre>cd path-to-where-you-want-to-keep-this-stuff
git clone git@github.com:cplusplus/LWG.git issues
git clone -b gh-pages git@github.com:cplusplus/LWG.git issues-gh-pages
cd issues
mkdir mailing</pre>
</blockquote>

<h2>Build issues software</h2>
<p>Do this after the initial setup, and then again whenever the source 
code (in <code>issues/src</code>) changes.</p>
<blockquote>
  <pre>cd issues
bin\build_pgms</pre>
</blockquote>

<h2>Add or change issues</h2>
<p>There is one source file per issue, in <code>issues/xml</code>. The file
<code>issues/xml/lwg-template.xml</code> can be used as a template to start a 
new issue. Use any text editor to edit the files.</p>
<p>Commit files locally as you update them:</p>
<blockquote>
  <pre>cd issues\xml
edit-as-needed
git commit -a -m&quot;your commit message here&quot;</pre>
</blockquote>
<p>Verify your changes had the desired effect by regenerating the 
issues lists and inspecting your changes:</p>
<blockquote>
  <pre>cd issues
bin\build_lists</pre>
</blockquote>
<p>Once you are happy with your changes, push them up to the GitHub 
public repository:</p>
<blockquote>
  <pre>cd issues
push</pre>
</blockquote>
<p>And finally, publish the new version of the lists on the web:</p>
<blockquote>
  <pre>cd issues
bin\update_lists</pre>
</blockquote>

<h2>Update meta-data</h2>
<p>The files in <code>issues/meta-data</code> need to be updated whenever 
there is a new draft of the working paper.</p>
<p>To do this, we need an up-to-date copy of the data in Annex F in a file <code>bin/annex-f</code>.</p>
<p>This can be more or less automatically generated (on a Unix system):</p>
<ol>
<li>Get a current copy of the source for the standard, and build it.  (These instructions assume that it's in <code>$WG21/draft/source</code>)</li>
<li>Generate <code>annex-f</code> using:
<ul>
<li><code>cd $WG21/draft/source ; grep newlabel *.aux | sed 's/\\newlabel{\([^}]*\)}.*TitleReference {\([^}]*\)}.*/\1 \2/' | grep -v "aux:tab:" | grep -v "aux:fig:" | sed 's/\(.*\).aux://' | grep -v '^\\' | sort > $WG21/issues/annex-f</code>
</li>
</ul>
</li>
</ol>
<p>Inspect the resulting file to see if looks reasonable.  I usually compare it to the previous version of <code>annex-f</code> as well.</p>
<p>Check whether entries starting with <code>defns.</code> are contained as well (Previous versions of the working
draft pdf did not have corresponding section numbers)</p>
</li>
</ol>
<p>Once the <code>annex-f</code> file exists in the proper format, perform the following steps:</p>
<ol>
<li>
<p>Copy file <code>annex-f</code> into the <code>bin</code> directory.</p>
</li>
<li>
<p>Execute the file <code>bin/build_section_data.bat</code>. This will produce the files <code>bin/index</code> and
<code>bin/section.data</code></p>
</li>
<li>
<p>Double-check that both files look OK. Especially take care to compare <code>bin/section.data</code> with
<code>meta-data/section.data</code> for suspicious changes.</p>
</li>
<li>
<p>If you are happy with the deltas, replace the
the current <code>meta-data/section.data</code> by the freshly generated <code>bin/section.data</code>.
</p>
</li>
</ol>

<h2>Generate Issues Lists for a Mailing</h2>
<p>We no longer include lists of issues, accepted/resolved issues, and rejected/closed issues in each mailing.
However, we still generate these lists, and send them to Keld for posting. These documents are produced directly by the software above.</p>
<p>The following steps should be pursued by <i>only</i> the Library Working Group chair, or someone delegated the
responsibility for publishing the issues lists by the Library Working Group chair.  They are recorded for future
reference to ease the burden on incoming chairs.</p>
<ol>
<li>inspect <tt>git branch</tt> to confirm that you are on the <tt>master</tt> branch</li>
<li><tt>git pull</tt> any last changes that may have been committed by others at github</li>
<li>Confirm that the issues data is in its publishable state</li>
<li>Push the current branch to github with a pre-mailing commit message</li>
    <ol>
    <li><code>git commit -a -m&quot;<i>commit message</i>&quot;</code></li>
    <li><code>git push</code></li>
    </ol>
<li>Fork a new branch to hold the final mailing with <code>git checkout -b <i>branch-name</i></code></li>
<li>Update <tt>xml/lwg-issues.xml</tt> with:</li>
    <ol>
    <li>The final 'R' revision of the list (provisional lists use a 'D')</li>
    <li>The current date</li>
    </ol>
<li>Confirm that the following <code>xml/lwg-issues.xml</code> information is correct:</li>
    <ol>
    <li>The LWG chair contact address (unlikely to change)</li>
    <li>The mailing title</li>
    <li>No new edits are needed to the boiler-plate text (changes are rare)</li>
    <li>The revision history is up to date for the <b><i>preceding</i></b> mailing</li>
    <li>(this mailing's revision history will be generated by the software)</li>
    </ol>
<li>Generate the lists only - do <b>not</b> run the generate-<i>and-publish</i> script above</li>
<li>Inspect the generated lists in the <tt>mailing</tt> directory</li>
<li>Correct any problems, and repeat the process until satisfied</li>
<li>Commit changes to git branch, with a suitable commit message</li>
<li>Zip the whole <tt>mailing</tt> directory, and email it to Keld Simmonsen</li>
</ol>
<p>Now it is time to prepare the branch for the next mailing.  This work should be completed <i>before</i> merging back to master.</p>
<ol>
<li>Replace <tt>metadata/lwg-toc.old.html</tt> with <tt>mailing/lwg-toc.html</tt> (note the name change, adding <tt>.old</tt></li>
<li>Update <tt>xml/lwg-issues.xml</tt> with:</li>
    <ol>
    <li>The provisional 'D' revision of the next list ('R' -&lt; 'D', and increment the number)</li>
    <li>An estimated date close to the next mailing</li>
    <li>The mailing title</li>
    <li>Update the revision history</li>
        <ol>
        <li>Copy the revision history for <i>just</i> the current mailing from any of the new N-docs)</li>
        <li>Paste the new revision under the <code>&lt;revision_history&gt;</code> tag</li>
        <li>Massage the html to match the xml of the entry below, e.g., change the <tt>revision</tt> text into an attribute with tag</li>
        <li>Change all the <tt>href</tt> tags in the section that you pasted into <tt>iref</tt> tags:</li>
        <ul><li>For example, change <tt>&lt;a href="lwg-active.html#2785"&gt;2785&lt;/a&gt;</tt> into <tt>&lt;iref ref="2785" /&gt;</tt></li></ul>
        </ol>
    </ol>
<li>Generate the lists only - do <b>not</b> run the generate-<i>and-publish</i> script above</li>
<li>Confirm that the document numbers are provisional, and the revision history is correct for the next mailing preview</li>
<li>Repeat the process until satisfied</li>
<li>Commit the git branch with an appropriate commit comment - <i>do not merge yet</i></li>
<li>Run <code>git checkout master</code> to switch back to the <tt>master</tt> branch
<li>Run <code>git pull</code> to ensure the current branch is in synch with github
<li>Run <code>git merge <i>branch-name</i></code> where <code><i>branch-name</i></code> matches the branch above</li>
<li>Resolve any conflicts (typically there are none)</li>
<li>Regenerate the issues lists again, to confirm that branch and tools are in a good state</li>
<li>Run <code>git status</code> to confirm there are no unexpected last minute edits that are not committed</li>
<li>Run <code>git push</code> to publish the updated <tt>master</tt> branch</li>
<li>Regenerate <i>and publish</i> the interim issues lists as described in the Add-an-issue process</li>
<li>Notify any collaborators to pull the updated <tt>master</tt> branch - the main list is open for business again</li>
</ol>

<hr>

<h2>Managing issues during a meeting</h2>
<p><i>preliminary notes here; more to come</i></p>
<p>Typical use was to move all Ready issues to Voting after the pre-meeting mailing, so that Issues moving to Ready during the meeting would not be confused.</p>
<p>Similarly, Voting issues could then easily move to Pending WP after the straw polls, and to WP once the new draft is available.</p>
<p>Likewise, you will want to move all the WP issues to C++17 once we approve the FDIS.</p>

<ul>
<li><code>list_issues &lt;status&gt;</code> will list all the issues with a specific status</li>
<li><code>set_status &lt;issue&gt; &lt;status&gt;</code> will set a single issue to a new status</li>
<li><code>update_status.sh &lt;status&gt;</code> will read a list of issue numbers from stdin and update the status of each of them.</li>
</ul>

<p>For example, <code>bin/list_issues "Ready" | bin/update_status.sh "Voting"</code> will change the status of all the "Ready" issues to "Voting" (w/o committing them)</p>
<p><b>Note:</b> <code>update_status.sh</code> (and <code>set_status</code>, which it calls), will happily set the status to whatever you want. Make sure you spell the new status correctly.</p>

</body></html>
